Naming and Ids

Docular follows a basic naming convention for each document object. This naming convention helps you split up your documentation objects into overviews, modules, module sections, items, and sub items.

What's in a Name?

Each document you create will eventually get a name and id after the parsing process. The id is the system id used and appears in the URL. The name attribute is used most often within the ui as user friendly text.

The "@id" value is what is considered along with the doc type to determine which bucket your documentation object goes into.

But in many examples (especially in Angular source code), there isn't an "@id", just a "@name". This is done out of convenience. The "@name" key value pair will be copied into the "@id" attribute if one is not provided. Therefore, you can quickly just give the name and have it be both the name and the id so it appears in the documentation title and serves as a unique identifier for the document.

The Two Main Buckets for Docs

At the top level, there are two major bucket types:

  1. Overview : This bucket holds general documentation that lives outside of modules
  2. Module : This holds documentation relevant to a specific module

Putting Docs into the Overview Bucket

First note that all the docs in this section of the tutorial are in the "overview" bucket. In the little nav area in the upper left hand corner you can see each of the docs in this section.

To get a doc into the overview bucket for a documentation section, do this:

/**
 * @doc overview
 * @id myId
 * @name This is just a title
 * @description Here is where I put all my
 * crazy overview documentation.
 *
 * ## I can use markdown here!
 */


The key part is the "@doc overview". The "overview" doctype tells Docular this doc is going into the general "overview" bucket regardless of what the "@id" or "@name" is.

Notice here we specify an "@id" and a "@name". The "@name" is user friendly text shown in the UI, whereas the "@id" attribute becomes the system utilized id and shows up in the url. And again, having "@doc overview" is where the magic occurs to put this into a general "overview" bucket of documentation.

It is possible to rank these overview documentation objects which is helpful for creating ordered step by step documenation such as this tutorial.

Putting Docs into Modules

Here is the default naming pattern:

module . module section : item . sub-item

Module and module section patterns are mostly self explanatory so we should dicuss item and sub-item a bit more in depth. First note that sub-item is optional. It gives you one more level of grouping and relationship. A good way to use this extra grouping would be to create a base element and then extend it. So your base element would be item and your extensions would be sub-item . Of course it is really up to you what conventions you want to you use!

So in general the combination of item or item . sub-item , could just be considered the unique id for this object within the module and module section .

Examples

Here are a few examples of sticking docs into the "itemView" module within different module sections like "service", "factory", "global", and "directive":

  1. @name itemView.service:items
  2. @name itemView.factory:user
  3. @name itemView.global:parseUsers
  4. @name itemView.directive:input
  5. @name itemView.directive:input.checkbox
  6. @name itemView.directive:input.select
REMEMBER! You are actually encouraged to only use the @name attribute to store the "id" and it will automatically populate into the "@id" field during parsing

Picture This

Here is a picture with labels that indicate the different parts of the naming pattern for AngularJS Input CheckBox Directive and how they are represented in the UI:

@name ng . directive : input . checkbox

For another example, the "input" directive right above the "input.checkbox" directive would simply be:

@name ng . directive : input

WARNING : The @ngdoc Documentation Plugin is a Cheater

So the naming convention above is what should generally be followed, however AngularJS has additional conventions that are enforced that do not follow the typical naming conventions but that still do put their document objects into modules and module-sections.

For instance, @name ng.$anchorScroll looks incomplete, but extra rules in the documentation plugin see the dollar sign ( $ ) and automatically assume that this is a service and turn it into @name ng.service:$anchorScroll .

Feel free to take advantage of this if you please or just stick the naming convention mentioned above.